home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / telecomm / bbs / ddbbs101.lha / Developer / DreamDoor / Doc / DreamDoor.doc next >
Encoding:
Text File  |  1995-03-10  |  15.9 KB  |  643 lines
  1. TABLE OF CONTENTS
  2.  
  3. DreamDoor.library/InitDoor
  4. DreamDoor.library/CloseDoor
  5. DreamDoor.library/SendString
  6. DreamDoor.library/Prompt
  7. DreamDoor.library/InquirePointers
  8. DreamDoor.library/DisplayFile
  9. DreamDoor.library/YesNo
  10. DreamDoor.library/ScanUserbase
  11. DreamDoor.library/UpdateStructures
  12. DreamDoor.library/XprSend
  13. DreamDoor.library/XprReceive
  14. DreamDoor.library/GetLrp
  15. DreamDoor.library/SetLrp
  16. DreamDoor.library/GetKey
  17. DreamDoor.library/ScanFileDirs
  18. DreamDoor.library/FlagFile
  19. DreamDoor.library/Disconnect
  20. DreamDoor.library/DDCommand
  21. DreamDoor.library/ResetIdle
  22. DreamDoor.library/Relogin
  23. DreamDoor.library/JoinConference
  24. DreamDoor.library/ChangeMsgBase
  25. DreamDoor.library/IntCommand
  26. DreamDoor.library/CheckKey
  27. DreamDoor.library/LineEditor
  28. DreamDoor.library/InitDoor
  29.  
  30.    NAME
  31.     InitDoor - Initialize door
  32.  
  33.    SYNOPSIS
  34.     dif = InitDoor(node)
  35.      D0             A0
  36.  
  37.         struct DIFace *InitDoor(char *)
  38.  
  39.    FUNCTION
  40.     Allocates all required structures, ports and messages. You should
  41.     call this at the beginning of door.
  42.  
  43.    EXAMPLE
  44.         InitDoor(argv[1]);
  45.  
  46.    INPUTS
  47.     node - The ASCII (!!) value of the node number.
  48.  
  49.    RESULT
  50.     dif - Ptr to an initialized DIFace structure or NULL if
  51.           DayDream's doorport isn't open.
  52.  
  53.    SEE ALSO
  54.     CloseDoor
  55. DreamDoor.library/CloseDoor
  56.  
  57.    NAME
  58.     CloseDoor - Shutdown door and delete messages, ports and DIFace.
  59.  
  60.    SYNOPSIS
  61.     CloseDoor(dif)
  62.                   D0
  63.  
  64.     void CloseDoor(struct DIFace *);
  65.  
  66.    FUNCTION
  67.     You *MUST* call this function to close door. This deletes all
  68.     structures created by InitDoor() and tells DayDream that door
  69.     has finished it's job.
  70.  
  71.    NOTE
  72.     This call will close the doorport, so you won't be able to send
  73.     cmd's to DayDream anymore, but the door can still do other tasks.
  74.     So it is NOT necessary to quit right after doing a CloseDoor()
  75.     call!
  76.  
  77.     !!IMPORTANT!!
  78.     It is *NOT* possible to re-initialise door by calling InitDoor()
  79.     after doing CloseDoor()
  80.  
  81.    EXAMPLE
  82.     CloseDoor(dif);
  83.  
  84.    INPUTS
  85.     dif - A pointer to the DIFace structure returned by InitDoor()
  86.  
  87.    SEE ALSO
  88.     InitDoor
  89.  
  90. DreamDoor.library/SendString
  91.  
  92.    NAME
  93.     SendString - Type String
  94.  
  95.    SYNOPSIS
  96.     SendString(dif, string)
  97.                    D0   A0
  98.  
  99.     void SendString(struct DIFace *, char *);
  100.  
  101.    FUNCTION
  102.     Prints specified string of characters to remote user's display,
  103.     local screen or both. Possible ANSI codes will be automatically
  104.     stripped, if user has chosen an ASCII display mode. When in need
  105.     of changing line, string only needs to contain a linefeed, carriage
  106.     return (ASCII 13) will be inserted automatically.
  107.  
  108.    EXAMPLE
  109.     SendString(dif,"Hello World!");
  110.  
  111.    INPUTS
  112.     dif - A pointer to the DIFace structure returned by InitDoor()
  113.         string - A pointer to the null-terminated string containing text
  114.          to print.
  115.  
  116. DreamDoor.library/Prompt
  117.  
  118.    NAME
  119.     Prompt - Prompt for user input
  120.  
  121.    SYNOPSIS
  122.     success = Prompt(dif, buffer, length, flags, default)
  123.         D0               D0   A0      D1      D2     D3
  124.  
  125.         int Prompt(struct DIFace *, char *, ULONG, ULONG, char *)
  126.  
  127.    FUNCTION
  128.     Prompts user to enter a string. Length will  be restricted as
  129.     requested by the door. Full support for ANSI cursor sequences
  130.     is given, so that user can easily move through the string and
  131.     modify as required.
  132.  
  133.    EXAMPLE 
  134.     stat = Prompt(dif,GSTR,13,DPF_FILENAME,"Marsu jee!");
  135.  
  136.    INPUTS
  137.     dif - A pointer to the DIFace structure returned by InitDoor()
  138.     buffer - Pointer to the buffer, where the final string will be
  139.          inserted. 
  140.     length - Maximum length
  141.     flags - DPF_HIDDEN = Hidden mode, print *'s instead of real chars.
  142.         DPF_NOCRLF = Don't print CR+LF after receiving result code.
  143.         DPF_FILENAME = Don't allow any chars illegal in filenames.
  144.     default - Default string or NULL
  145.  
  146.    RESULT
  147.     success - 0L if carrier lost, 1L if successfull.
  148.  
  149. DreamDoor.library/InquirePointers
  150.  
  151.    NAME
  152.     InquirePointers - Inquire Structure Pointers
  153.  
  154.    SYNOPSIS
  155.     InquirePointers(dif, pointers)
  156.         D0              D0   A0
  157.  
  158.     void InquirePointers(struct DIFace *, struct DDPointers *)
  159.  
  160.    FUNCTION
  161.     This command will return with pointers to several significant
  162.     system structures, such as user structure etc.
  163.     Be careful when editing stuff in those pointers, because DayDream
  164.     uses same memoryblocks! You can also find out with this function 
  165.     if DayDream is in local mode.
  166.  
  167.    EXAMPLE
  168.     InquirePointers(d,pointermem);
  169.  
  170.    NOTE 
  171.     _NEVER_ use these pointers after DayDream has closed it's Doorport!
  172.  
  173.    INPUTS
  174.     dif - A Pointer to DIFace returned by InitDoor()
  175.     pointers - A pointer to allocated memoryblock where the pointers
  176.            are placed.
  177.  
  178. DreamDoor.library/DisplayFile
  179.  
  180.    NAME
  181.     DisplayFile - Display ANSI of ASCII-file
  182.  
  183.    SYNOPSIS
  184.     DisplayFile(dif, filename, flags)
  185.                     D0   A0        D1
  186.  
  187.        void DisplayFile(struct DIFace *, char *, ULONG)
  188.  
  189.    FUNCTION
  190.     This command outputs an ASCII or ANSI file into remote terminal,
  191.     local screen or both.
  192.  
  193.    EXAMPLE
  194.     DisplayFile(d,"s:user-startup",DDF_SHOWERROR);
  195.  
  196.    INPUTS
  197.     dif - A Pointer to the DIFace returned by InitDoor()
  198.     filename - A pointer to the filename to show.
  199.     flags - DDF_ADDEXTENSION = automatically add .GFX/.TXT.
  200.         DDF_SHOWERROR = In case file couldn't be found, show a
  201.                 visible error message instead of quiting
  202.                 quietly.
  203.  
  204. DreamDoor.library/YesNo
  205.  
  206.     NAME
  207.     YesNo - Prompt user for simple yes or no
  208.  
  209.     SYNOPSIS
  210.     result = YesNo(dif,default)
  211.     D0             d0  d1
  212.  
  213.     int YesNo(struct DIFace *, ULONG);
  214.  
  215.     FUNCTION
  216.     This function asks user to answer a simple yes or no question.
  217.     Door program must type the question by itself, since  all this
  218.     function outputs is an ASCII string "Yes" or "No" based on the
  219.     user's answer.
  220.  
  221.     EXAMPLE
  222.     poro = YesNo(d,DYESNO_NO);
  223.  
  224.     INPUTS
  225.     dif - A Pointer to the DIFace returned by InitDoor()
  226.     default - Default answer. 1 = Yes, 0 = No.
  227.  
  228.     RESULT
  229.     result - 0 = No, 1 = Yes, -1 = Carrier lost.
  230.  
  231. DreamDoor.library/ScanUserbase
  232.  
  233.     NAME
  234.     ScanUserbase - Scan Userbase for Scecified User Account
  235.  
  236.     SYNOPSIS
  237.     offset = ScanUserbase(dif, name)
  238.     D0                    D0   A0
  239.  
  240.     LONG ScanUserbase(struct DIFace *, char *);
  241.  
  242.     FUNCTION
  243.     This function scans user database (UserBase.DAT) in order to find
  244.     the specified account. Match can be made in real name or handle.
  245.     Operation is fully non-case-sensitive.
  246.  
  247.     INPUTS
  248.     dif - A Pointer to the DIFace returned by InitDoor()
  249.     name - A Pointer to the Handle or Name to user to be scanned.
  250.  
  251.     RESULT
  252.     offset - An offset to the matching account. -1 if account not
  253.          found.
  254.  
  255. DreamDoor.library/UpdateStructures
  256.  
  257.     NAME
  258.     UpdateStructures - Update DayDream Data Structures
  259.  
  260.     SYNOPSIS
  261.     UpdateStructures(dif)
  262.                          D0
  263.  
  264.     void UpdateStructures(struct *DIFace);
  265.  
  266.     FUNCTION
  267.     This function must be called after any DayDream structure has
  268.     been modified. Please remember to observe extreme cautiousness,
  269.     since careless modifications will lead to a system crash.
  270.  
  271.     INPUTS
  272.     dif - A Pointer to the DIFace returned by InitDoor()
  273.  
  274. DreamDoor.library/XprSend
  275.  
  276.     NAME
  277.     XprSend - Send file(s) w/ Xpr-Protocol.
  278.  
  279.     SYNOPSIS
  280.     XprSend(dif, files, default path)
  281.         D0   A0     A1
  282.  
  283.     void XprSend(struct *DIFace, char *, char *);
  284.  
  285.     FUNCTION
  286.     This function allows door to send file(s) to user using currently
  287.     selected XPR-Protocol. 
  288.  
  289.     INPUTS
  290.     dif - A Pointer to the DIFace returned by InitDoor()
  291.     files - Pointer to a data block, consisting of NULL-terminated to
  292.         be transferred. End of the block will be signaled with a $FF
  293.         (Byte). 
  294.     default path - Pointer to a valid AmigaDOS pathname. Files with no
  295.                path spec will be looked for in this directory.
  296.  
  297. DreamDoor.library/XprReceive
  298.  
  299.     NAME
  300.     XprReceive - Receive file(s) w/ Xpr-Protocol
  301.  
  302.     SYNOPSIS
  303.     XprReceive(dif, path)
  304.            D0   A0
  305.  
  306.     void XprReceive(struct *DIFace, char *);
  307.  
  308.     FUNCTION
  309.     This function allows door to receive files from user using currently
  310.     selected XPR-Protocol.
  311.  
  312.     INPUTS
  313.     dif - A Pointer to the DIFace returned by InitDoor()
  314.     path - path to receive files.
  315.  
  316. DreamDoor.library/GetLrp
  317.  
  318.     NAME
  319.     GetLrp - Gets last read pointer from specified message base.
  320.  
  321.     SYNOPSIS
  322.     result = GetLrp(dif, conf, base)
  323.     D0        D0   D1    D2
  324.  
  325.     ULONG *GetLrp(struct *DIFace, ULONG, ULONG);
  326.  
  327.     FUNCTION
  328.     Gets last read pointer of current user from specified message base.
  329.  
  330.     INPUTS
  331.     dif - A Pointer to the DIFace returned by InitDoor()
  332.     conf - Conference number
  333.     base - Message base number
  334.     
  335.     RESULT
  336.     result - Last read pointer is returned.
  337.  
  338. DreamDoor.library/SetLrp
  339.  
  340.     NAME
  341.     SetLrp - Sets last read pointer
  342.  
  343.     SYNOPSIS
  344.     SetLrp(dif, conf, base, lrp)
  345.            D0   D1    D2    D3
  346.  
  347.     void SetLrp(struct *DIFace, ULONG, ULONG, ULONG);
  348.  
  349.     FUNCTION
  350.     Gets last read pointer of current user to specified message base.
  351.  
  352.     INPUTS
  353.     dif - A Pointer to the DIFace returned by InitDoor()
  354.     conf - Conference number
  355.     base - Message base number
  356.     lrp - New Last read pointer
  357.  
  358. DreamDoor.library/GetKey
  359.  
  360.     NAME
  361.     GetKey - Gets a character from local console or remote terminal
  362.  
  363.     SYNOPSIS
  364.     result = GetKey(dif, flags)
  365.     D0         D0   D1
  366.     
  367.     ULONG *GetKey(struct *DIFace, ULONG);
  368.  
  369.     FUNCTION
  370.     This function simply waits for a single keypress from either the
  371.         local console or remote terminal. After receiving a character,
  372.         this function will immediately return with no further activity.
  373.  
  374.     INPUTS
  375.     dif - A Pointer to the DIFace returned by InitDoor()
  376.     flags - currently understands these flags:
  377.                 HOTKEY_SHOWCHAR - Show pressed character
  378.         HOTKEY_ADDLF    - Insert CRLF after received character
  379.         HOTKEY_CURSOR    - Check for cursor keys (250=up etc) 
  380.  
  381.     RESULT
  382.     result - NULL if carrier lost or received character
  383.  
  384. DreamDoor.library/ScanFileDirs
  385.  
  386.     NAME
  387.     ScanFileDirs - Vittu tän kans palaa taulu!
  388.  
  389.     SYNOPSIS
  390.     result = ScanFileDirs(dif, conf, pattern, hook, userdata)
  391.     D0              D0   D1    A0       A1    A2
  392.  
  393.     ULONG *ScanFileDirs(struct *DIFace, ULONG, char *, APTR, ULONG);
  394.  
  395.     FUNCTION
  396.     This function will scan all the file directories in the specified
  397.         conference and see if any of the files matches with given string;
  398.         wildcards allowed, of course. When a match is found, this routine
  399.         will call a hook routine with path, name and size of the file 
  400.         as it's parameters allowing it to process the file in any wanted
  401.         way. After the hook has returned, scanning will or will not be
  402.         continued depending on whether the search string contained any
  403.         wildcards (if it didn't, no more than one match is possible).
  404.     If hook is null, internal fileflagging hook of DayDream will be
  405.     used.
  406.  
  407.     INPUTS
  408.     dif - A Pointer to the DIFace returned by InitDoor()
  409.     conf - Conference number
  410.     pattern - Pointer to the search string, wildcards allowed.
  411.     hook - Pointer to the hook routine to call:
  412.  
  413.                Hook(Path, Filename, Size, UserData);
  414.                     A0    A1        D0    D1
  415.  
  416.                >WARNING< HOOK ROUTINE MAY ABSOLUTELY NOT
  417.                MODIFY ANY SYSTEM   REGISTERS  UNLESS THE
  418.                ORIGINAL VALUES ARE RETURNED BEFORE EXIT!
  419.  
  420.                If this is NULL, use File tagging-routines of DayDream.
  421.     userdata - User data variable - will be given to Hook() routine 
  422.                    as provided here. This will just pass through DD and
  423.                    doesn't have any effect on DD's operation. With this
  424.            field you can easily pass some data to your hook.
  425.  
  426.     NOTE
  427.     You may not call functions using DIF when in hook.
  428.     
  429.     RESULT
  430.     result - 0 - Operation successful
  431.                  1 - Not enough memory (only 2048 bytes needed)
  432.                  2 - Specified conference not found
  433.                  3 - Specified conference doesn't have any file directories
  434.  
  435. DreamDoor.library/FlagFile
  436.  
  437.     NAME
  438.     FlagFile - Add file to the download request
  439.  
  440.     SYNOPSIS
  441.     result = FlagFile(dif, path, file, flags, size)
  442.     D0                D0   A0    A1    D1     D2
  443.  
  444.     ULONG = FlagFile(struct *DIFace, char *, char *, ULONG, ULONG);
  445.  
  446.     FUNCTION
  447.     This function will add a file to the download request. Current dload
  448.         request will be checked first to avoid possible duplicate entries.
  449.         If no duplicate entry or other errors occurred, file will be added
  450.         to the filechain.
  451.  
  452.     INPUTS
  453.     dif - A Pointer to the DIFace returned by InitDoor()
  454.     path - Pointer to the path where the file to be added can be
  455.                found. PATH MUST END WITH A SLASH ('/') OR COLON (':')!
  456.     file - pointer to the actual filename
  457.     flags - FLAGFILE_FREE if file is a free download
  458.     size - Size of the file.
  459.  
  460.     RESULT
  461.     result - 0 - Operation successful
  462.                  1 - Duplicate entry found
  463.                  2 - File ratio problems
  464.                  3 - Byte ratio problems
  465.                  4 - Not enough memory
  466.  
  467. DreamDoor.library/Disconnect
  468.  
  469.     NAME
  470.     Disconnect - Kick some ass
  471.  
  472.     SYNOPSIS
  473.     Disconnect(dif)
  474.            D0
  475.  
  476.     void Disconnect(struct *DIFace);
  477.  
  478.     FUNCTION
  479.     This function will disconnect user from BBS.
  480.  
  481.     INPUTS
  482.     dif - A Pointer to the DIFace returned by InitDoor()
  483.  
  484. DreamDoor.library/DDCommand
  485.  
  486.     NAME
  487.     DDCommand - Run DayDream Command
  488.  
  489.     SYNOPSIS
  490.     DDCommand(dif, command)
  491.           D0   A0
  492.  
  493.     void DDCommand(struct *DIFace, char *);
  494.  
  495.     FUNCTION
  496.     Allows use of DayDream's commands (also external ones)
  497.  
  498.     INPUTS
  499.     dif - A Pointer to the DIFace returned by InitDoor()
  500.     command - Command to be executed.
  501.     
  502. DreamDoor.library/ResetIdle
  503.  
  504.     NAME
  505.     ResetIdle - Resets idle counter
  506.  
  507.     SYNOPSIS
  508.     ResetIdle(dif)
  509.           D0
  510.  
  511.     void ResetIdle(struct DIFace *);
  512.     
  513.     FUNCTION
  514.     This function will reset the idle-counter. Useful for doors
  515.     having own serial/console routines, before and after archiving
  516.     something etc. Note that hotkey, prompt etc. routines reset
  517.     the idle counter automatically.
  518.  
  519.     INPUTS
  520.     dif - A Pointer to the DIFace returned by InitDoor()
  521.  
  522. DreamDoor.library/Relogin
  523.  
  524.     NAME
  525.     Relogin - VITTU SE ON JUST NIINKU SE ON! HAHA!
  526.  
  527.     SYNOPSIS
  528.     Relogin(dif)
  529.         D0
  530.  
  531.     void Relogin(struct DIFace *);
  532.  
  533.     FUNCTION
  534.     Same as CloseDoor(), except this will relogin user to the
  535.         system.
  536.  
  537.     INPUTS
  538.     dif - A Pointer to the DIFace returned by InitDoor()
  539.     
  540.  
  541. DreamDoor.library/JoinConference
  542.  
  543.     NAME
  544.     JoinConference - Joins specified Conference
  545.  
  546.     SYNOPSIS
  547.     JoinConference(dif, conf, flags)
  548.             D0    D1    D2
  549.  
  550.     void JoinConference(struct DIFace *, ULONG, ULONG);
  551.  
  552.     FUNCTION
  553.     Joins specified conference.
  554.  
  555.     INPUTS
  556.     dif - A Pointer to the DIFace returned by InitDoor()
  557.     conf - number of conference to join
  558.     flags - JOINCONFF_ASKNEW - Ask new conference if requested conference
  559.                    doesn't exist
  560.         JOINCONFF_QUICK - Do not load any conference specific data
  561.                   etc. If you use this, you must join back
  562.                   to the original conference before quitting
  563.                   door.
  564.         JOINCONFF_SKIPTXT - Skip JoinConference.TXT|GFX 
  565.  
  566. DreamDoor.library/ChangeMsgBase
  567.  
  568.     NAME
  569.     ChangeMsgBase - Change current message base
  570.  
  571.     SYNOPSIS
  572.     ChangeMsgBase(dif, base, flags)
  573.               D0    D1    D2
  574.  
  575.     void ChangeMsgBase(struct DIFace *, ULONG, ULONG);
  576.  
  577.     FUNCTION
  578.     This function changes the current msg base.
  579.  
  580.     INPUTS
  581.     dif - A Pointer to the DIFace returned by InitDoor()
  582.     base - number of base to enter
  583.     flags - CBMF_SHOWMENU - Show menu if base = 0
  584.         CBMF_NOSTATUS - Do not display msgbase status
  585.     
  586. DreamDoor.library/IntCommand
  587.  
  588.     NAME
  589.     IntCommand - Run internal DayDream Command
  590.  
  591.     SYNOPSIS
  592.     DDCommand(dif, command)
  593.           D0   A0
  594.  
  595.     void DDCommand(struct *DIFace, char *);
  596.  
  597.     FUNCTION
  598.     Allows use of DayDream's commands (only internals)
  599.  
  600.     INPUTS
  601.     dif - A Pointer to the DIFace returned by InitDoor()
  602.     command - Command to be executed.
  603.  
  604. DreamDoor.library/CheckKey
  605.  
  606.     NAME
  607.     CheckKey - Gets a character from local console or remote terminal
  608.  
  609.     SYNOPSIS
  610.     result = CheckKey(dif)
  611.     D0               D0 
  612.     
  613.     ULONG *CheckKey(struct *DIFace, ULONG);
  614.  
  615.     FUNCTION
  616.     Checks if there's character in receive buffer and if so, returns
  617.     it.
  618.  
  619.     INPUTS
  620.     dif - A Pointer to the DIFace returned by InitDoor()
  621.  
  622.     RESULT
  623.     result - NULL if nothing or received character
  624.  
  625. DreamDoor.library/LineEditor
  626.  
  627.     NAME
  628.     LineEditor - Edit file using DD's built-in line editor.
  629.  
  630.     SYNOPSIS
  631.     LineEditor(dif, file)
  632.                D0    D1
  633.     
  634.     void LineEditor(struct *DIFace, char *);
  635.  
  636.     FUNCTION
  637.     Edit and create text file using DD's built-in line editor.
  638.  
  639.     INPUTS
  640.     dif - A Pointer to the DIFace returned by InitDoor()
  641.     file - Pointer to the filename to edit
  642.  
  643.